OLE Automation

OLE Automation with ClassiX®.

• Programming a foreign application
• COM objects in ClassiX®
• Collections and objects
• Events
• Arrays
• Constants
• Optional parameters
• Performance
• Annex

ClassiX® offers the possibility to control and program external applications via OLE automation. In the following, we will look specifically at Microsoft's Office products. If you have already programmed Visual Basic, you will have no difficulties to do this in InstantView®. The most important tool is the object catalog offered by the Microsoft applications. It can be accessed within the application by pressing Alt+F11 under 'View' > 'Object Catalog'. It lists all classes and enumerations of the selected application in the left window. If you click on one of them, it shows the methods, attributes and events contained in the right-hand window and a short syntax explanation with description below. You can also access the detailed help via the context menu.

Programming a foreign application

The first step in programming a foreign application is to understand the application. The best way to do this is to try to understand the object model of the application. The object catalog or literature, such as 1. and the Internet, see 2. Information on VB programming of Office 2000 can be found under 3.

Fig. 1 The object catalog of Microsoft Word in the VB(A) editor

To start programming, you need to know the name of an initial class. All Office applications offer the class 'Application', which is used to program the application itself. There are also classes for the corresponding documents, e.g. Word.Document or Excel.Sheet. All these class names can also be found in the Windows registry under the key 'HKEY_CLASSES_ROOT'. All applications and file types registered in the system are listed here. All directly accessible classes of Word can be found e.g. under Word.*, where the asterisk stands for the class name. To program a Word document, for example, the class Word.Document is available. If there is a number after the class name, this number indicates the version. An entry without a number always indicates the latest version.

COM objects in ClassiX®

With this information you can now start programming. Since all COM objects in ClassiX® are of type CX_COM_OBJECT, a new object of type CX_COM_OBJECT is created first. This object offers the method CreateFromProgID, which establishes the connection with the application. The name of the required class is passed to the method as a parameter.

Example:

Now the object doc represents the class Word.Document. All data fields and methods of this class can now be used. To use a method the parameters are put on the stack and then the corresponding method is called with Call():

Example:

The values of the data fields are set and read in a similar way. Each data field name is converted in two methods, once with 'Put' and once with 'Get' before the data field name. This can now be called like any other method:

Example:

Here the data field 'Password' is first set with 'PutPassword' and immediately afterwards read out again with 'GetPassword'. Now the string "secret" is on the stack.

Collections and objects

If a method or a data field returns an object, it is always of the type CX_COM_OBJECT, but represents the corresponding VB object and can be used just like any normal ClassiX® object.
If a collection is returned, it can also be used like a collection under ClassiX®. The 'Iterate' statement is the equivalent of 'For Each ... Next' loop in VB.

Example:

These instructions are in any case preferable to a normal loop with manual incrementing of an index, since they are smaller and much easier to read.

Events

Events offered by the external application can so far only be used in ClassiX® ActiveX controls, not yet in normal OLE automation.

Arrays

Arrays are not yet supported by the ClassiX® COM interface. This means that no arrays can be passed to methods of COM objects from ClassiX® , and no methods of COM objects can be called if they return arrays.

Constants

If an attribute or method returns a constant according to the documentation or object explorer, then this constant cannot be taken over in the form, because there are no constants in InstantView®. Instead, the integer value of the constant must be used in InstantView®. The value is displayed in the object explorer, for example. For the sake of readability, you can assign the value of a variable which gets the name of the constant, but then you have to take care that this variable is of course changeable.

Example:

Returns the type of the document (document, template, ...) as Enum WdDocumentType. In VB this is a constant, in InstantView® there is now an integer value on the stack which can be assigned to a variable.
To set an attribute, the same procedure is used, the value of the desired constant can be found in the object catalog and it is then simply set like any other attribute.

Example:

Here the letters in the selected area (the first 100 characters) are converted to upper case.

Optional parameters

Another difference between VB and InstantView® is the handling of function parameters. While VB supports optional parameters which can be omitted at will, in InstantView® only the last optional parameters can be omitted. Care must be taken to ensure that old values that could be interpreted as parameters are not accidentally left on the stack.

Although the SaveAs method understands various parameters, this InstantView® statement works because the file name is the first expected parameter. However, you should now make sure that the stack is empty, because any elements on the stack could be interpreted as the other parameters and you might get either unexpected results or an error message due to an incorrect type. The following VB statement is not possible in InstantView®:

Here SaveAs gets besides the file name a password, which is needed to open the document. In order to implement this instruction in InstantView®, the default values for all omitted parameters would have to be passed on:

The 0 here stands for the memory format, which by default is the Microsoft Word format. The FALSE parameter is the default value for the setting whether the document should be locked for comments.

Performance

Finally, a few notes on performance. Each time you call a method or set or get an attribute, it takes time. This means that navigating from one object to another can take a long time. If two calls are to be made from the target object, it is much more efficient to store the object once in a variable than to navigate back to it completely from the source class each time.

This applies in VB as well as in InstantView®.
Furthermore, variable accesses are always faster than an access expression to an attribute or a method of an object. This is particularly noticeable in loops, which is why you should avoid access expressions here and instead assign the return value of the access expression to a variable once before the loop.

Annex

Illustration of VB types on ClassiX®:

Byte, integer, long:	Integer
Single, double:	CX_NUMERIC
Currency:	CX_VALUE
String:	String
Variant:	The corresponding fix type
Boolean:	CX_BOOLEAN
Date:	CX_DATE/CX_TIME/CX_DATETIME
Object:	CX_COM_OBJECT
Array:	Not yet supported by ClassiX

Literature:

1
Microsoft Office 97 Visual Basic Programmer's Guide, Microsoft Press, 1997

2
http://www.microsoft.com/technet/treeview/default.asp?url=/TechNet/prodtechnol/office/proddocs/opg/appendixes/partapp.asp

3
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odeopg/html/deovroffice2000visualbasicprogrammersguide.asp